home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 001 / quotes / !SQ%a0Source / Other / ShortHDocs < prev    next >
Text File  |  1994-09-19  |  9KB  |  214 lines
  1. Small Help version 1.00
  2. ⌐ Sam Kington 8th August 1994
  3. This program is freeware, *not* public domain ù i.e., I retain copyright (see
  4. öBoring legal messageò)
  5.  
  6. What this program does
  7. **********************
  8.  
  9.    This program, or rather this set of library routines, allows you to
  10. compact the help messages contained in modules by using RISC OSæs internal
  11. dictionary: the routine FNprint goes through a string, replacing certain
  12. keywords with (much shorter) control codes, which will then be expanded by
  13. *Help, or more exactly expanded by OS_PrettyPrint called by *Help. The
  14. advantage of having these library routines is that a) you donæt have to
  15. re-invent the wheel and b) itæs more readable than hard-wiring the codes into
  16. the source code.
  17.  
  18.    The routines, being written in BASIC, are only usable from within the
  19. BASIC assembler.
  20.  
  21.    To use the routines, add the following lines somewhere near the beginning
  22. of the moduleæs source code (in the BASIC part, not the assembler part):
  23.       LIBRARY "%.ShortHelp"
  24.       PROCprettyprintinit
  25.    The exact ₧lename you use may be different; however, if you are going to
  26. use the routines regularly, you might as well put them in your Library, in
  27. which case you would use the ₧lename "%.ShortHelp". If you donæt know what a
  28. Library is, or whether you have one, you probably donæt have one, so it isnæt
  29. worth setting one up just for ShortHelp. (See your User Guide for more
  30. information about Libraries).
  31.    Afterwards, in the help part of the module source code, which will
  32. probably look something like this:-
  33.  
  34. .help_Command
  35.    EQUS  "Command does whatever this command is supposed to do."
  36.    EQUB  0
  37.  
  38. - replace it by the following:
  39.  
  40. .help_Command
  41.    EQUS  FNprint("Command does whatever this command is supposed to do.","Command")
  42.    EQUB  0
  43.    
  44.    In other words, replace the string by FNprint(<string>, <name of command).
  45.    
  46. OK, but how does this actually work?
  47. ************************************
  48.  
  49.    When *Help is called, it looks for the appropriate help string in the
  50. module code, and then sends it to a SWI called OS_PrettyPrint, which formats
  51. it correctly, breaking lines at spaces and correctly printing tabs.
  52. OS_PrettyPrint also uses an internal dictionary of regularly occurring text,
  53. and looks through the text for certain combinations of characters that mean
  54. öinsert dictionary entry hereò. If you have the PRMs, look at the entry for
  55. OS_PrettyPrint for a complete list of the dictionary entries (In the RISC OS
  56. 3 PRMs it's at pages 1-518 to 1-520; in the RISC OS 2 PRMs it's at pages 185
  57. to 187). If you donæt, a complete list follows at the end of this section.
  58.  
  59.    FNprint does the reverse: it scans the string for dictionary entries,
  60. replaces them by the control sequences (which are naturally much shorter,
  61. being only two characters rather than potentially dozens), which will then be
  62. expanded by *Help.
  63.  
  64.    For those who don't have the PRMs, here follows a short resume of what
  65. certain special characters mean:
  66.  
  67.    CR (ASCII 13) causes a newline to be generated.
  68.    TAB (ASCII 9) causes a tabulation to the next multiple of eight columns
  69.    SPACE (ASCII 31) is a hard space (i.e. the line won't break here).
  70.    ESC (ASCII 27) indicates a dictionary entry should be substituted.
  71.    
  72.    The default list of dictionary entries follows:
  73.    
  74.       0: special string
  75.       1: "Syntax: *"special string
  76.       2: " the "
  77.       3: "director"
  78.       4: "filing system"
  79.       5: "current"
  80.       6: " to a variable. Other types of value can be assigned with *"
  81.       7: "file"
  82.       8: "default"
  83.       9: "tion"
  84.       10: "*Configure"
  85.       11: "name"
  86.       12: " server"
  87.       13: "number"
  88.       14: "Syntax: *"special string" <"
  89.       15: " one or more files that match the given wildcard"
  90.       16: " and "
  91.       17: "relocatable module"
  92.       18: CR"*C(onfirm)"Tab"*Prompt for confirmation of each "
  93.       19: "sets the "
  94.       20: "Syntax: *"special string" [<disc spec.>]"
  95.       21: "}"CR"*V(erbose)"Tab"*Printinformation on each file "
  96.       23: "spriteLandscape [<XScale>[<YScale> [<Margin> [<Threshold>]]]]]"
  97.       24: " is used to print a hard copy of the screen on EPSON-"
  98.       25: "."CR"*Options: (use ~ to force off, eg. ~"
  99.       26: "printe"
  100.       27: "Syntax: *"special string"<filename>"
  101.       28: "select"
  102.       29: "xpression"
  103.       30: "Syntax: *"special string" ["
  104.       31: "sprite"
  105.       32: " displays"
  106.       33: "free space"
  107.       34: " {off}"
  108.       35: "library"
  109.       36: "parameter"
  110.       37: "object"
  111.       38: " all "
  112.       39: "disc"
  113.       40: " to "
  114.       41: " is "
  115.    
  116.    Note that there is no entry 22, and also that some entries require the
  117. previous CR to be included in the string. The special string is a string
  118. supplied along with the string to be expanded; in the case of *Help, the
  119. special string is the name of the command, so any time the sequence
  120. CHR$27+CHR$0 was found in any text produced by the command *Help Command,
  121. CHR$27+CHR$0 would be replaced by öCommandò. That is why you have to supply
  122. the name of the command to FNprint, so it can look for it and replace it
  123. accordingly.
  124.  
  125. Boring legal message
  126. ********************
  127.  
  128.    This application is freeware, that is, it can be distributed freely as
  129. long as only reasonable charges are made for media and distribution. I retain
  130. copyright on all program code and documentation.
  131.  
  132.    This software is supplied öasáisò: I make no warranty, expressed or
  133. implied, of the merchantability of this software or its ₧tness for any
  134. particular purpose. In no circumstances shall I be liable for any damage,
  135. loss of pro₧ts, or any indirect or consequential loss arising out of the use
  136. of this software or inability to use this software, even if I have been
  137. advised of the possibility of such loss.
  138.  
  139.    In other words, if your computer crashes, blows up, you lose all your work
  140. etc. all because of SmallHelp (unlikely I know), donæt blame me.
  141.  
  142. Distribution
  143. ************
  144.  
  145.    You should have two ₧les, ShortHelp and ShortHDocs. There may be other
  146. ₧les in the directory if ShortHelp has been supplied with another program,
  147. but ShortHelp doesnæt need them.
  148.  
  149.    If you are a PD library, an ftp site or whatever, simply distributing
  150. these routines as part of a single package, you should supply both of the
  151. ₧les intact, complete and without modi₧cation.
  152.  
  153.    You are allowed, and indeed encouraged, to use these routines in your own
  154. programs. You may make whatever modi₧cations you wish to the routinesæ code,
  155. provided you document the changes appropriately in this ₧le and in the
  156. source code. If you use the routines, it would be nice if you could tell me
  157. (see below for contact details); if you use them and distribute the end
  158. result, I would appreciate it if you could send me a copy (or tell me where I
  159. can get one). I will of course expect you to at least make a passing mention
  160. of the routines you used in the documentation.
  161.  
  162.    In other words, if you change anything, document the changes in the
  163. documentation and the source code; if you use it in your code, give me a
  164. credit and tell me (if possible) youæve done it.
  165.  
  166. About all these strange foreign characters in this ₧le
  167. *******************************************************
  168.  
  169.    OK, so if youære reading this on a PC or a Mac or another strange machine
  170. like that, you may be wondering what all these strange ae things are. Well,
  171. theyære quotes (sorry, there was another one), dashes, ligatures, etc.
  172. Honest. But not on all machines...
  173.    Basically, character sets are only standard up to character 127, which is
  174. basically alphanumerics and a few standard punctuation marks. Foreign
  175. characters, typographical oddities like quotes and ligatures, and other more
  176. obscure symbols are önon-standardò, and each computer often has its own idea
  177. of where they should go in the character set. So donæt worry: even if itæs
  178. hard to read on your current machine, it wonæt be on an Acorn machine. It may
  179. look slightly strange if youære using the System font, however.
  180.    But why am I using these strange characters in the ₧rst place? Well,
  181. theyære in the character set and they look nice in an outine font, and Iæve
  182. written a program called Smart Quotes (sorry for the plug) that substitutes
  183. these sort of characters automatically, and Iæve got it turned on at the
  184. moment...
  185.  
  186. How to contact me
  187. *****************
  188.  
  189. All bug-reports, suggestions, comments or indeed any feedback at all will be
  190. welcomed. Hereæs how to get to me:
  191.  
  192. E-mail     : 9262861k@arts.gla.ac.uk, 926286ki@udcf.gla.ac.uk during term-time
  193.              These should be OK until June 1996
  194.              At Christmas, Easter and during the summer, you can get me at
  195.              wombat@altern.com, wombat@email.teaser.com or sam@altern.com, in order
  196.              of preference (that is, if mail bounces off one of these or I donæt
  197.              answer within a week send to the next one).
  198.  
  199. Snail-mail : My term-time address, at least until June 1995, is:
  200.              Sam Kington
  201.              Flat 2/1
  202.              44 Hotspur Street
  203.              Glasgow G20 8NL
  204.              SCOTLAND
  205.              
  206.              Again, a backup is the home address ù anything that goes here will get
  207.              to me eventually.
  208.              Sam Kington
  209.              Merlhiot
  210.              24420 Savignac les Eglises
  211.              FRANCE
  212.  
  213. Term-time is October to June, with bits off at Christmas (3 weeks) and
  214. Easter (4 weeks).